|
|
TransliterateText |
||||
| Header: | Script.h | Carbon status: | Supported | |
Converts characters from one subscript to the closest possible approximation in a different subscript within the same 2-byte script system.
OSErr TransliterateText (
Handle srcHandle,
Handle dstHandle,
SInt16 target,
SInt32 srcMask,
ScriptCode script
);
A handle to the source text to be transliterated. The TransliterateText function converts all of the text that you pass it in this parameter. It determines the length of the source text (in bytes) from the handle size.
A handle to a buffer that, upon completion of the call, contains the transliterated text.
Before calling TransliterateText, allocate a handle (of any size) to pass in the dstHandle parameter. The length of the transliterated text may be different (as when converting between 1-byte and 2-byte characters), and TransliterateText sets the size of the destination handle as required. It is your responsibility to dispose of the destination handle when you no longer need it.
A value that specifies what kind of text the source text is to be transliterated into.
The low byte of the target is the format to convert to (the target format). It determines what form the text should be transliterated to. In all script systems, there are two currently supported values for target format: smTransAscii and smTransNative. In 2-byte script systems, additional values are recognized.
The high byte is the target modifier; it contains modifiers, whose meanings depend on the script code, providing additional formatting instructions. In all script systems, there are two values for target modifier: smTransLower and smTransUpper.
A bit array that specifies which parts of the source text are to be transliterated. A bit is set for each script system or subscript that should be converted to the target format. In all script systems, the srcMask parameter may have the following values: smMaskAscii, smMaskNative, and smMaskAll. In 2-byte script systems, additional values are recognized.
A value that specifies the script system of the text to be transliterated. Constants for all defined script codes are listed in
A result code.
Transliteration is the conversion of text from one form or subscript to another within a single script system. In the Roman script system, transliteration means case conversion. In 2-byte script systems, it is the automatic conversion of characters from one subscript to another. One common use for transliteration is as an initial stage of text conversion for an input method.
TransliterateText also performs uppercasing and lowercasing, with consideration for regional variants, in the Roman script system and on Roman text within 2-byte script systems.
Because the low-ASCII character set (character codes $20–$7F) is present in all script systems, you could theoretically use the TransliterateText function to convert characters from one script system into another completely different script system. You could transliterate from a native subscript into ASCII under one script system, and then transliterate from that ASCII into a native subscript under a different script system. Such a function is not recommended, however, because of the imperfect nature of phonetic translation. Furthermore, many script systems do not support transliteration from native subscripts to ASCII.
TransliterateText may move memory; your application should not call this function at interrupt time.
If you pass smCurrentScript in the script parameter, the conversion performed by TransliterateText can be affected by the state of the font force flag. It is unaffected by the international resources selection flag.
Transliteration of a block of text does not work across script-run boundaries. Because the TransliterateText function requires transliteration tables that are in a script system’s international resources, you need to call it anew for each script run in your text.
Currently, the Roman version of TransliterateText checks the source mask only to ensure that at least one of the bits corresponding to the smMaskAscii and smMaskNative constants is set.
The Arabic and Hebrew versions of TransliterateText perform case conversion only. They allow the target values smTransAscii and smTransNative only; otherwise, they behave like the Roman version.
The TransliterateText tables for 1-byte script systems reside in the script’s string-manipulation ('itl2') resource, so they can reflect region-specific or language-specific differences in uppercase conventions. If the string-manipulation resource does not include these tables, TransliterateText exits without doing anything.
The TransliterateText tables for 2-byte script systems reside in the script’s transliteration ('trsl') resource. If the 'trsl' resource does not include these tables, TransliterateText exits without doing anything.
The Japanese, Traditional Chinese, and Simplified Chinese versions of TransliterateText have two modes of operation. If either smMaskAscii or smMaskNative is specified in the source mask, and if the target is smTransAscii, and if either of the target modifiers is specified, TransliterateText performs the specified case conversion on both 1-byte and 2-byte Roman letters. Otherwise, TransliterateText performs conversions according to the target format values. Any combination of source masks and target format is permitted.
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
© 2000 Apple Computer, Inc. (Last Updated 6/30/2000)